{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "intro",
   "metadata": {},
   "source": [
    "# Diagnosing SSL Issues in EdgarTools\n",
    "\n",
    "If you're getting SSL certificate errors when using EdgarTools, this notebook will help you diagnose the problem and find a solution.\n",
    "\n",
    "## Common SSL Error Messages\n",
    "\n",
    "You might see errors like:\n",
    "- `SSLCertVerificationError: certificate verify failed`\n",
    "- `CERTIFICATE_VERIFY_FAILED`\n",
    "- `unable to get local issuer certificate`\n",
    "\n",
    "These typically occur in **corporate networks** that use SSL inspection proxies, or in environments with custom certificate configurations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "step1",
   "metadata": {},
   "source": [
    "## Step 1: Run the Diagnostic Tool\n",
    "\n",
    "EdgarTools includes a built-in SSL diagnostic tool that checks your connection to SEC.gov:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "run-diagnostic",
   "metadata": {},
   "outputs": [],
   "source": [
    "from edgar import diagnose_ssl\n",
    "\n",
    "# Run diagnostics and display results\n",
    "result = diagnose_ssl()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "understanding",
   "metadata": {},
   "source": [
    "## Understanding the Results\n",
    "\n",
    "The diagnostic runs 5 tests:\n",
    "\n",
    "| Test | What it checks |\n",
    "|------|---------------|\n",
    "| **1. DNS Resolution** | Can your computer find SEC.gov's IP address? |\n",
    "| **2. TCP Connection** | Can you connect to SEC.gov on port 443? |\n",
    "| **3. SSL Handshake** | Does the SSL certificate verify correctly? |\n",
    "| **4. HTTP (default SSL)** | Can you make an HTTPS request with standard settings? |\n",
    "| **5. HTTP (your settings)** | Can you make an HTTPS request with your configured settings? |\n",
    "\n",
    "### Key Insight: Tests 4 vs 5\n",
    "\n",
    "- **Test 4** uses default SSL verification (like a fresh Python install)\n",
    "- **Test 5** uses YOUR configured settings (e.g., if you've called `configure_http(verify_ssl=False)`)\n",
    "\n",
    "If Test 4 fails but Test 5 passes, your workaround is working!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "programmatic",
   "metadata": {},
   "source": [
    "## Step 2: Check the Results Programmatically\n",
    "\n",
    "You can inspect the diagnostic result object to understand what's happening:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "check-results",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the result without displaying (useful for scripting)\n",
    "result = diagnose_ssl(display=False)\n",
    "\n",
    "# Check if SSL is working\n",
    "print(f\"SSL OK: {result.ssl_ok}\")\n",
    "print(f\"Diagnosis: {result.diagnosis}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "check-details",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check specific test results\n",
    "net = result.network_tests\n",
    "\n",
    "print(f\"DNS resolved: {net.dns_resolved} (IP: {net.dns_ip})\")\n",
    "print(f\"TCP connected: {net.tcp_connected}\")\n",
    "print(f\"SSL handshake success: {net.ssl_handshake.success if net.ssl_handshake else 'N/A'}\")\n",
    "print(f\"HTTP with default SSL: {net.http_request_ok}\")\n",
    "print(f\"HTTP with your settings: {net.configured_http_ok}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "check-proxy",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check if a corporate proxy was detected\n",
    "if result.network_tests.ssl_handshake:\n",
    "    if result.network_tests.ssl_handshake.is_corporate_proxy:\n",
    "        print(\"Corporate SSL inspection proxy detected!\")\n",
    "        print(\"Your network intercepts HTTPS traffic and replaces certificates.\")\n",
    "    else:\n",
    "        print(\"No corporate proxy detected.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fix-section",
   "metadata": {},
   "source": [
    "## Step 3: Apply the Fix\n",
    "\n",
    "Based on the diagnosis, here are the common solutions:\n",
    "\n",
    "### Solution A: Disable SSL Verification (Quick Fix)\n",
    "\n",
    "If you're on a corporate network with SSL inspection, this is often the easiest solution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fix-disable-ssl",
   "metadata": {},
   "outputs": [],
   "source": [
    "from edgar import configure_http\n",
    "\n",
    "# Disable SSL verification\n",
    "configure_http(verify_ssl=False)\n",
    "\n",
    "# Now test if it works\n",
    "from edgar import Company\n",
    "apple = Company(\"AAPL\")\n",
    "print(f\"Success! Got {apple.name}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fix-ca",
   "metadata": {},
   "source": [
    "### Solution B: Add Corporate CA Certificate (More Secure)\n",
    "\n",
    "If your IT department can provide your organization's root CA certificate:\n",
    "\n",
    "```python\n",
    "import os\n",
    "os.environ[\"REQUESTS_CA_BUNDLE\"] = \"/path/to/corporate-ca.pem\"\n",
    "\n",
    "# Then import and use edgar normally\n",
    "from edgar import Company\n",
    "```\n",
    "\n",
    "Or set it as an environment variable before running Python:\n",
    "```bash\n",
    "export REQUESTS_CA_BUNDLE=\"/path/to/corporate-ca.pem\"\n",
    "python your_script.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "recommendations",
   "metadata": {},
   "source": [
    "## Step 4: Check Recommendations\n",
    "\n",
    "The diagnostic tool provides specific recommendations based on what it finds:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "show-recommendations",
   "metadata": {},
   "outputs": [],
   "source": [
    "result = diagnose_ssl(display=False)\n",
    "\n",
    "if result.recommendations:\n",
    "    print(\"Recommendations:\")\n",
    "    for i, rec in enumerate(result.recommendations, 1):\n",
    "        print(f\"\\n{i}. {rec.title}\")\n",
    "        print(f\"   {rec.description}\")\n",
    "        if rec.code_snippet:\n",
    "            print(f\"\\n   Code:\\n   {rec.code_snippet[:100]}...\")\n",
    "else:\n",
    "    print(\"No issues found - SSL is working correctly!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "env-info",
   "metadata": {},
   "source": [
    "## Bonus: Environment Information\n",
    "\n",
    "You can also inspect the environment details that were gathered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "show-env",
   "metadata": {},
   "outputs": [],
   "source": [
    "result = diagnose_ssl(display=False)\n",
    "\n",
    "env = result.environment\n",
    "print(f\"Python: {env.python_version}\")\n",
    "print(f\"Platform: {env.platform}\")\n",
    "print(f\"EdgarTools: {env.edgartools_version}\")\n",
    "print(f\"httpx: {env.httpx_version}\")\n",
    "print(f\"certifi: {env.certifi_version}\")\n",
    "print(f\"cryptography: {env.cryptography_version or 'Not installed'}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "show-cert-config",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check certificate and proxy configuration\n",
    "cert = result.certificate_config\n",
    "print(\"Certificate Configuration:\")\n",
    "print(f\"  REQUESTS_CA_BUNDLE: {cert.requests_ca_bundle or 'Not set'}\")\n",
    "print(f\"  SSL_CERT_FILE: {cert.ssl_cert_file or 'Not set'}\")\n",
    "print(f\"  certifi bundle: {cert.certifi_path}\")\n",
    "\n",
    "if result.proxy_config:\n",
    "    proxy = result.proxy_config\n",
    "    print(\"\\nProxy Configuration:\")\n",
    "    print(f\"  HTTP_PROXY: {proxy.http_proxy or 'Not set'}\")\n",
    "    print(f\"  HTTPS_PROXY: {proxy.https_proxy or 'Not set'}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cli",
   "metadata": {},
   "source": [
    "## Command Line Usage\n",
    "\n",
    "You can also run the diagnostic from the command line:\n",
    "\n",
    "```bash\n",
    "python -m edgar.diagnose_ssl\n",
    "```\n",
    "\n",
    "This is useful for troubleshooting in environments where Jupyter isn't available."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "help",
   "metadata": {},
   "source": [
    "## Need More Help?\n",
    "\n",
    "- **Documentation**: [SSL Verification Guide](https://github.com/dgunning/edgartools/blob/main/docs/guides/ssl_verification.md)\n",
    "- **GitHub Issues**: [Report a problem](https://github.com/dgunning/edgartools/issues)\n",
    "- **Common causes**: Corporate firewalls, VPNs, outdated certifi package"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
